home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / ab20 / ab20_archive / text / cmanual.lzh / ACM2.lzh / Requesters / Requesters.doc < prev    next >
Text File  |  1990-01-30  |  24KB  |  650 lines
  1. 5    REQUESTERS
  2.  
  3. 5.1  INTRODUCTION
  4.  
  5. Requesters are boxes filled with some sort of information which
  6. the user need to respond to. It can be as simple as a question
  7. to insert a disk in the internal drive, or a fully functional
  8. file requester. Requesters are like small windows with some
  9. gadgets connected to it, and they will first disappear when the
  10. user has "satisfied the request".
  11.  
  12.  
  13.  
  14. 5.2  DIFFERENT TYPES OF REQUESTERS
  15.  
  16. There exist three different types of requesters:
  17. - System requesters
  18. - Application requesters
  19. - Double-menu requesters
  20.  
  21.  
  22.  
  23. 5.2.1  SYSTEM REQUESTERS
  24.  
  25. System requesters are opened and maintained by Intuition, and
  26. your program has no control over them. If the user, for
  27. example, is trying to load a file from drive df1:, and there is
  28. no disk present, the operating system would open the following
  29. request:
  30.  
  31.   -----------------------------------
  32.   | System Request ============[*][*]
  33.   -----------------------------------
  34.   | No disk present              |  |
  35.   | in unit  1                   |  |
  36.   |                              |  |
  37.   | ---------         ---------- |  |
  38.   | | Retry |         | Cancel | |  |
  39.   | ---------         ---------- |  |
  40.   --------------------------------[*]
  41.  
  42.  
  43. One important thing about System requesters is that they are
  44. like small windows. You can move around them, push them behind
  45. or in front of other windows/requesters, and resize them.
  46.  
  47.  
  48.  
  49. 5.2.2  APPLICATION REQUESTERS
  50.  
  51. This is the type of requester your program can open. They can
  52. be of any size (limited only by the size of the screen), and
  53. can be as simple or as complicated as you want.
  54.  
  55. If you only want a Yes/No (True/False) requester you can call
  56. the function AutoRequest(), and Intuition will open and take
  57. care of the rest. If you on the other hand want a more
  58. sophisticated requester you need to declare and initialize a
  59. Requester structure with your requirements, and call the
  60. function Request().
  61.  
  62. It is important to notice that an Application requester can not
  63. be moved around, resized etc (the window containing the
  64. requester can still, of course, be moved around and resized).
  65. It is only the System requesters, and the very simple
  66. requesters opened by the AutoRequest function, which acts like
  67. small windows.
  68.  
  69. There is also one other big difference. When an Application
  70. requester has been activated the user can no longer select
  71. gadgets connected to the window. The window has been "frozen".
  72. Eg. try Example4, and you will notice that you can not select
  73. the close-window gadget as long as the requester is active. On
  74. the other hand, if a System requester has been activated, the
  75. user can still click on the close-window gadget, and a
  76. CLOSEWINDOW message is sent.
  77.  
  78.  
  79.  
  80. 5.2.3  DOUBLE-MENU REQUESTERS
  81.  
  82. Double-menu requesters are like normal Application requesters
  83. except that they will open first, and only, when the user
  84. double-clicks on the mouse menu button. To create a Double-menu
  85. requester you need to declare and initialize a Requester
  86. structure, and then call the function SetDMRequest(). Whenever
  87. the user from now on double-clicks on the menu button on the
  88. mouse, the requester will be opened. Call the function
  89. ClearDMRequest() when you do not want the user to be able to
  90. open the requester any more.
  91.  
  92. Only one DM-requester may be connected to each window.
  93.  
  94.  
  95.  
  96. 5.3  GRAPHICS FOR REQUESTERS
  97.  
  98. You can render a requester in two different ways. You can
  99. either tell Intuition what you want, and everything is rendered
  100. for you, or you can supply Intuition with your own customized
  101. Bitmap (which has been rendered by yourself).
  102.  
  103. If you want Intuition to draw the requester for you, you only
  104. need to decide what colour the background of the requester
  105. should be filled with, and declare and initialize one or more
  106. Border and IntuiText structures.
  107.  
  108. If you supply your own customized Bitmap Intuition will not
  109. draw anything itself. That means that all gadget connected to
  110. that requester does not need to have any Border/IntuiText/Image
  111. structures connected to them, since Intuition will not bother
  112. about them.
  113.  
  114.  
  115.  
  116. 5.4  POSITION
  117.  
  118. The requester can either be positioned relative to the top left
  119. corner of the window, or relative to the pointer position. If
  120. you want to position the requester relative to the window, you
  121. simply set the LeftEdge and TopEdge variables as desired. If
  122. you, on the other hand, want it relative to the pointer
  123. position, set the POINTREL flag, and initialize RelLeft and
  124. RelTop as desired.
  125.  
  126.  
  127.  
  128. 5.5  REQUESTERS AND GADGETS
  129.  
  130. When you create a requester, except when you call the function
  131. AutoRequest(), you need to connect at least one gadget to the
  132. requester. Gadgets connected to a requester works exactly the
  133. same as gadgets connected to a window but with two important
  134. differences:
  135.  
  136. 1. Every gadget connected to a requester MUST have the
  137.    REQGADGET flag set in the GadgetType field.
  138.  
  139. 2. At least one gadget must satisfy the request, which means at
  140.    least one gadget must have the ENDGADGET flag set in the
  141.    Activation field. (Once a gadget with an ENDGADGET flag set
  142.    is selected, the requester is satisfied, and will close.)
  143.  
  144. Remember that the user should always be able to find a safe way
  145. to leave the requester without affecting anything. The "way out
  146. gadget" (CANCEL, RESUME etc) should also always be placed on
  147. the right side in the requester. Here is an example:
  148.  
  149.   ---------------------------------------
  150.   | System Request ================[*][*]
  151.   ---------------------------------------
  152.   | Do you really want to quit?      |  |
  153.   |                                  |  |
  154.   |                                  |  |
  155.   | -------                   ------ |  |
  156.   | | Yes |                   | No | |  |
  157.   | -------                   ------ |  |
  158.   ------------------------------------[*]
  159.  
  160. Note that the Yes/True/Retry button is always on the left side
  161. and that the No/False/Cancel button is always on the right side.
  162.  
  163. IMPORTANT! Make sure that the Gadgets are inside the
  164. requester, since Intuition will not do any boundary checking.
  165.  
  166.  
  167.  
  168. 5.6  SIMPLE REQUESTERS
  169.  
  170. If you just want a simple requester with a True/False (or just
  171. False) option, you can use the function AutoRequest(). You give
  172. Intuition some information about how the requester should look
  173. like (height, text etc), and Intuition takes care of everything
  174. else. It opens the requester, put your program to rest, and
  175. when finished, returns a boolean value which tells your program
  176. what the user selected. If the user selected the left gadget
  177. (positive) it returns TRUE, and if the user selected the right
  178. gadget (negative) it returns FALSE.
  179.  
  180. Example:
  181.  
  182.   result = AutoRequest( window, info_text, pos_text, neg_text,
  183.                         pos_IDCMP, neg_IDCMP, width, height );
  184.  
  185.   window:    Pointer to a window if there exist one, else NULL.
  186.  
  187.   info_text: Pointer to an IntuiText structure containing the
  188.              "body text".
  189.  
  190.   pos_text:  Pointer to an IntuiText structure containing the
  191.              "positive text". Eg: "TRUE", "YES", "RETRY" etc.
  192.              (Optional)
  193.  
  194.   neg_text:  Pointer to an IntuiText structure containing the
  195.              "negative text". Eg: "FALSE", "NO", "CANCEL" etc.
  196.  
  197.   pos_IDCMP: The IDCMP flags which satisfy the "positive"
  198.              gadget. (The flag RELVERIFY is already set.)
  199.  
  200.   pos_IDCMP: The IDCMP flags which satisfy the "negative"
  201.              gadget. (The flag RELVERIFY is already set.)
  202.  
  203.   width:     How many pixels wide the requester should be.
  204.  
  205.   height:    How many lines high the requester should be.
  206.  
  207.  
  208.  
  209. 5.7  OPEN A REQUESTERS
  210.  
  211. If you want to use a more complicated requester instead of the
  212. Simple requester you need to:
  213.  
  214. 1. Declare and initialize a Requester structure with your
  215.    requirements.
  216.  
  217. 2. Declare and initialize the Gadget structures which are
  218.    going to be connected to the requester.
  219.  
  220. 3. Call the function Request() in order to display the
  221.    requester as a normal requester, or call the function
  222.    SetDMRequest() to enable the user to bring up the requester
  223.    as a Double-menu requester.
  224.  
  225.  
  226.  
  227. 5.7.1  INITIALIZE A REQUESTER
  228.  
  229. If you want to use a requester you need to declare and
  230. initialize a Requester structure which look like this:
  231.  
  232. struct Requester
  233. {
  234.   struct Requester *OlderRequest;
  235.   SHORT LeftEdge, TopEdge;
  236.   SHORT Width, Height;
  237.   SHORT RelLeft, RelTop;
  238.   struct Gadget *ReqGadget;
  239.   struct Border *ReqBorder;
  240.   struct IntuiText *ReqText;
  241.   USHORT Flags;
  242.   UBYTE BackFill;
  243.   struct Layer *ReqLayer;
  244.   UBYTE ReqPad1[32];
  245.   struct BitMap *ImageBMap;
  246.   struct Window *RWindow;
  247.   UBYTE ReqPad2[36];
  248. };
  249.  
  250. OlderRequest:      Initialized and maintained by Intuition.
  251.                    Set to NULL.
  252.  
  253. LeftEdge, TopEdge: Position of the requester relative to the
  254.                    top left corner of the window (if the
  255.                    POINTREL flag is not set).
  256.  
  257. Width, Height:     Size of the requester.
  258.  
  259. RelLeft, RelTop:   If the POINTREL flag is set, these values
  260.                    describes the position of the requester
  261.                    relative to the pointer.
  262.  
  263. ReqGadget:         Pointer to the first gadget in the linked
  264.                    list. Remember, there must exist at least
  265.                    one gadget connected to the requester with
  266.                    the ENDGADGET flag set.
  267.  
  268. ReqBorder:         Pointer to a Border structure used to render
  269.                    the requester.
  270.  
  271. ReqText:           Pointer to an IntuiText structure used to
  272.                    print text in the requester.
  273.  
  274. Flags:             There exist two flags which you may set:
  275.  
  276.                    POINTREL: Set this flag if you want to
  277.                              position the requester relative to
  278.                              the pointer. Set the RelLeft,
  279.                              RelTop as desired.
  280.  
  281.                    PREDRAWN: If you supply with your own
  282.                              customized Bitmap set this flag,
  283.                              and Intuition will not try to draw
  284.                              anything itself.
  285.  
  286.                    Intuition sets these flags:
  287.                    
  288.                    REQACTIVE:    This flag is set when the
  289.                                  requester is activated, and
  290.                                  cleared when the requester is
  291.                                  closed (deactivated).
  292.  
  293.                    REQOFFWINDOW: This flag is set if the
  294.                                  requester is active and
  295.                                  positioned outside the window.
  296.                                  (The user has maybe shrinked
  297.                                  the window so it is smaller
  298.                                  than you thought.)
  299.  
  300.                    SYSREQUEST:   This flag is set if the
  301.                                  requester is of the type
  302.                                  System requester.
  303.  
  304. BackFill:          Colour register used to fill the requester
  305.                    with before any drawing takes place. For
  306.                    example, if you want to render the graphics
  307.                    on an orange background, you set the
  308.                    BackFill field to 3 (orange, normal WB
  309.                    colours).
  310.  
  311. ReqLayer:          Pointer to the Layer structure for this
  312.                    requester. Initialized and maintained by
  313.                    Intuition. Set to NULL.
  314.  
  315. ReqPad1:           Initialized and maintained by Intuition. Set
  316.                    to NULL. (Used by the system.)
  317.  
  318. ImageBMap:         If the bit PREDRAWN is set, this field
  319.                    should contain a pointer to a customized
  320.                    Bitmap, else NULL.
  321.  
  322. RWindow:           Initialized and maintained by Intuition.
  323.                    Set to NULL. (Used by the system, points
  324.                    back to the Window which this requester is
  325.                    connected to.)
  326.  
  327. ReqPad2:           Initialized and maintained by Intuition. Set
  328.                    to NULL. (Used by the system.)
  329.  
  330.  
  331. Here is an example of how to initialize a Requester structure:
  332.  
  333. struct Requester my_requester=
  334. {
  335.   NULL,             /* OlderRequester, used by Intuition.   */
  336.   40, 20,           /* LeftEdge, TopEdge, 40 pixels out, 20 */
  337.                     /* lines down.                          */
  338.   320, 100,         /* Width, Height, 320 pixels wide, 100  */
  339.                     /* lines high.                          */
  340.   0, 0,             /* RelLeft, RelTop, Since POINTREL flag */
  341.                     /* is not set, Intuition ignores these  */
  342.                     /* values.                              */
  343.   &my_first_gadget, /* ReqGadget, pointer to the first      */
  344.                     /* gadget.                              */
  345.   &my_border,       /* ReqBorder, pointer to a Border       */
  346.                     /* structure.                           */
  347.   &my_text,         /* ReqText, pointer to a IntuiText      */
  348.                     /* structure.                           */
  349.   NULL,             /* Flags, no flags set.                 */
  350.   3,                /* BackFill, draw everything on an      */
  351.                     /* orange background.                   */
  352.   NULL,             /* ReqLayer, used by Intuition. Set to  */
  353.                     /* NULL.                                */
  354.   NULL,             /* ReqPad1, used by Intuition. Set to   */
  355.                     /* NULL.                                */
  356.   NULL,             /* ImageBMap, no predrawn Bitmap. Set   */
  357.                     /* to NULL. (The PREDRAWN flag was not  */
  358.                     /* set.)                                */
  359.   NULL,             /* RWindow, used by Intuition. Set to   */
  360.                     /* NULL.                                */
  361.   NULL              /* ReqPad2, used by Intuition. Set to   */
  362.                     /* NULL.                                */
  363. };
  364.  
  365.  
  366. If you would like to supply your own customized and predrawn
  367. Bitmap, instead of letting Intuition render the requester you
  368. need to:
  369.  
  370. 1. Set the flag PREDRAWN in the Flags field.
  371.  
  372. 2. Set the ImageBMap to point at your BitMap structure.
  373.  
  374. Remember that Intuition will now not draw anything for you. The
  375. ReqBorder, ReqText and BackFill variables are ignored, and
  376. should therefore be set to NULL. Intuition will also not render
  377. the gadgets connected to the requester. Because of this it is
  378. important that the rendering of the Bitmap is done carefully,
  379. and that the graphics correspond to where the gadgets are etc.
  380.  
  381.  
  382.  
  383. 5.7.2  HOW TO ACTIVATE AN APPLICATION REQUESTER
  384.  
  385. If you have declared and initialized a Requester structure you
  386. only need to call the function Request() in order to activate
  387. it.
  388.  
  389. Example:
  390.  
  391.   result = Request( my_requester, my_window );
  392.  
  393.   my_requester: Pointer to the Requester structure.
  394.  
  395.   my_window:    Pointer to the Window structure which the
  396.                 requester should be connected to.
  397.  
  398.   result:       Boolean value returned. If Intuition could
  399.                 successfully open the requester the function
  400.                 returns TRUE, else (something went wrong, not
  401.                 enough memory etc) the function returns FALSE.
  402.  
  403.  
  404. If you on the other hand would like the requester to be a
  405. Double-menu requester you should call the function
  406. SetDMRequest(), which will allow the user to activate the
  407. requester by double clicking the mouse menu button.
  408.  
  409. Example:
  410.  
  411.   result = SetDMRequest( my_window, my_requester );
  412.  
  413.   my_window:    Pointer to the Window structure which the
  414.                 requester should be connected to.
  415.  
  416.   my_requester: Pointer to the Requester structure.
  417.  
  418.   result:       Boolean value returned. If Intuition could
  419.                 successfully open the requester the function
  420.                 returns TRUE, else (some thing went wrong, not
  421.                 enough memory or the a DM requester is already
  422.                 connected to the window etc) the function
  423.                 returns FALSE.
  424.  
  425. You can after you have called the SetDMRequest() function
  426. successfully, take away the ability for the user to open the
  427. requester by calling the function ClearDMRequest().
  428.  
  429. Example:
  430.  
  431.   result = ClearDMRequest( my_window );
  432.  
  433.   my_window:    Pointer to the Window structure which the
  434.                 requester is connected to.
  435.  
  436.   result:       If the function could disable the user to
  437.                 activate the DM-requester it returns TRUE, else
  438.                 (something went wrong, the requester is in use
  439.                 etc) it returns FALSE.
  440.  
  441.  
  442.  
  443. 5.8  IDCMP FLAGS
  444.  
  445. There exist three IDCMP flags which are special for the
  446. requesters. When a requester is activated you can, if you want
  447. to, receive a message telling you that a requester was
  448. activated. This is especially useful if you are using Double-
  449. menu requesters, since this is the only way to check if the
  450. requester was opened.
  451.  
  452. If you want to get a message every time a requester is
  453. activated, you need to set the flag REQSET in the IDCMPFlags
  454. field in the NewWindow structure. Set the flag REQCLEAR if you
  455. want to receive a message every time a requester is
  456. deactivated. See Example5 for more details.
  457.  
  458. There exist also one special IDCMP flag called REQVERIFY. If
  459. you set this flag in the IDCMPFlags field in the NewWindow
  460. structure your program will receive a message when the user is
  461. trying to activate a Double-menu requester. The interesting
  462. thing about this flag is that the requester will not be opened
  463. until your program has replied, ReplyMsg(). Your program can
  464. therefore finish of something (like finish of with drawing
  465. something etc) before the requester is displayed, and when your
  466. program is ready, it can reply, and the requester is activated.
  467. See Example6 for more information.
  468.  
  469.  
  470.  
  471.  
  472. 5.9 FUNCTIONS
  473.  
  474. Here are some commonly used functions:
  475.  
  476. AutoRequest()
  477.  
  478.   This function opens a Simple requester. Intuition will
  479.   automatically activate it and take care of the response from
  480.   the user. It will return TRUE if the left gadget was
  481.   selected, and FALSE if the right gadget was selected.
  482.  
  483.   Synopsis:  result = AutoRequest( my_window, info_txt, pos_txt,
  484.                                    neg_txt, pos_IDCMP, neg_IDCMP,
  485.                                    width, height );
  486.  
  487.   my_window: (struct Window *) Pointer to a window if there
  488.              exist one, else NULL.
  489.  
  490.   info_txt:  (struct IntuiText *) Pointer to an IntuiText
  491.              structure containing the "body text".
  492.  
  493.   pos_txt:   (struct IntuiText *) Pointer to an IntuiText
  494.              structure containing the "positive text". Eg:
  495.              "TRUE", "YES", "RETRY" etc. (Optional)
  496.  
  497.   neg_txt:   (struct IntuiText *) Pointer to an IntuiText
  498.              structure containing the "negative text". Eg:
  499.              "FALSE", "NO", "CANCEL" etc.
  500.  
  501.   pos_IDCMP: (long) IDCMP flags which satisfy the "positive"
  502.              gadget. (The flag RELVERIFY is already set.)
  503.  
  504.   pos_IDCMP: (long) IDCMP flags which satisfy the "negative"
  505.              gadget. (The flag RELVERIFY is already set.)
  506.  
  507.   width:     (long) How many pixels wide the requester should
  508.              be.
  509.  
  510.   height:    (long) How many lines high the requester should
  511.              be.
  512.  
  513.   result:    (long) Boolean value. The function returns TRUE if
  514.              the positive gadget was satisfied, and FALSE if
  515.              the negative gadget was satisfied.
  516.  
  517.  
  518. Request()
  519.  
  520.   This function activates a requester connected to a window.
  521.   
  522.   Synopsis:     result = Request( my_requester, my_window );
  523.  
  524.   my_requester: (struct Requester *) Pointer to the Requester
  525.                 structure.
  526.  
  527.   my_window:    (struct Window *) Pointer to the Window
  528.                 structure which the requester should be
  529.                 connected to.
  530.  
  531.   result:       (long) Boolean value returned. If Intuition
  532.                 could successfully open the requester the
  533.                 function returns TRUE, else (something went
  534.                 wrong, not enough memory etc) the function
  535.                 returns FALSE.
  536.  
  537.  
  538. EndRequest()
  539.  
  540.   This function deactivates a requester which has been
  541.   activated.
  542.   
  543.   Synopsis:     EndRequest( my_requester, my_window );
  544.  
  545.   my_requester: (struct Requester *) Pointer to the Requester
  546.                 structure which will be removed.
  547.  
  548.   my_window:    (struct Window *) Pointer to the Window
  549.                 structure which the requester is connected to.
  550.  
  551.  
  552. SetDMRequest()
  553.  
  554.   This function allows the user to activate a Double-menu
  555.   requester by clicking twice on the mouse menu button.
  556.  
  557.   Synopsis:  result = SetDMRequest( window, requester );
  558.  
  559.   window:    (struct Window *) Pointer to the Window structure
  560.              which the requester should be connected to.
  561.  
  562.   requester: (struct Requester *) Pointer to the Requester
  563.              structure.
  564.  
  565.   result:    (long) Boolean value returned. If Intuition could
  566.              successfully open the requester the function
  567.              returns TRUE, else (something went wrong, not
  568.              enough memory or a DM requester is already
  569.              connected to the window, etc) the function returns
  570.              FALSE.
  571.  
  572.  
  573. ClearDMRequest()
  574.  
  575.   This function disables a Double-menu requester. The user can
  576.   not open the requester any more.
  577.   
  578.   Synopsis:     result = ClearDMRequest( my_window );
  579.  
  580.   my_window:    (struct Window *) Pointer to the Window
  581.                 structure which the requester is connected to.
  582.                 The DMRequest pointer in the Window structure
  583.                 is set to NULL.
  584.  
  585.   result:       (long) If the function could disable the
  586.                 DM-requester it returns TRUE, else (something
  587.                 went wrong, the requester is in use etc) it
  588.                 returns FALSE.
  589.  
  590.  
  591.  
  592. 5.10  EXAMPLES
  593.  
  594. Example1
  595.   This example opens a Simple requester by calling the function
  596.   AutoRequest. It displays a message "This is a very simple
  597.   requester!", and has only one gadget connected to it (on the
  598.   right side of the requester) with the text "OK".
  599.  
  600. Example2
  601.   Same as Example1, except that the requester displays a
  602.   message "Do you really want to quit?", and allows the user to
  603.   choose between "Yes" and "No". The program  will continue to
  604.   reopen the requester until the user has chosen "Yes".
  605.  
  606. Example3
  607.   Same as Example1, except that this requester displays a
  608.   message "Insert a disk in any drive!", and allows the user to
  609.   choose between "Yes" and "No". The program will continue to
  610.   reopen the requester until the user has chosen "Yes" or
  611.   inserted a disk.
  612.  
  613. Example4
  614.   This program will open a normal window which is connected to
  615.   the Workbench Screen. The window will use all System Gadgets,
  616.   and will close first when the user has selected the System
  617.   gadget Close window. Inside the window we have activated an
  618.   Application requester with a connecting gadget. The requester
  619.   will first be satisfied when the user has selected the
  620.   gadget, and will then be deactivated. The window can now be
  621.   closed.
  622.  
  623. Example5
  624.   Same as Example4, except that the requester is first
  625.   activated when the user double-clicks on the right mouse
  626.   button. This example shows how to create a Double-menu
  627.   requester, and how to monitor the IDCMP flags REQSET and
  628.   REQCLEAR.
  629.  
  630. Example6
  631.   Same as Example5, except that whenever the user double-
  632.   clicks on the right mouse button, we will receive a REQVERIFY
  633.   message, and first when we have replied, will the requester
  634.   be activated. This example shows how to use the REQVERIFY
  635.   flag.
  636.  
  637. Example7
  638.   This program will open a normal window which is connected to
  639.   the Workbench Screen. The window will use all System Gadgets,
  640.   and will close first when the user has selected the System
  641.   gadget Close window. Inside the window we have activated an
  642.   Application requester with three connecting gadgets. Two are
  643.   Boolean gadgets ("OK and "CANCEL"), and one is a String
  644.   gadget.
  645.  
  646. Example8
  647.   Same as Example7, except that it is an Integer gadget.
  648.  
  649. Example9
  650.   Same as Example8, except that it is a Proportional gadget.